完整程式碼可在 GitHub 專案中找到：Finetune-30-days-demo / day-23

在 Day 21，我們有了 Model Card 與共享 API，能描述模型與支援搜尋/推薦。
在 Day 22，我們導入 MLflow Tracking，統一了實驗參數與指標的紀錄。

但這還不夠。
實際上，一個模型的生命週期應該包含：訓練 → 驗證 → 部署 → 替換 → 歸檔。
因此今天的任務，是將 MLflow Model Registry 與 Model Card 串接，建立一套「模型版本與階段管理」的治理雛形。

一、為什麼要有 Model Registry？

僅僅保存實驗結果，還無法回答這些問題：

• 哪一個版本的模型正在 Production？
• 如果新模型表現退步，怎麼 回滾？
• 如何保證「同一個 base_model」同時只有一個生產版本？

這正是 Model Registry 要解決的問題：
它幫我們建立清晰的版本編號（version）與階段標記（stage: Staging/Production/Archived），從而實現模型生命週期的有序管理。

二、模型生命週期設計

在這次優化後，每個模型會同時對應：

1. 一個 MLflow run（Day 22）
2. 一張 Model Card（Day 21）
3. 一個 Registry 版本與階段（今天的改進）

完整流程長這樣：

訓練完成 → MLflow run → 註冊到 Registry → Stage = Staging
    ↓
驗證通過 → 切換到 Production（舊版本自動歸檔）
    ↓
被替換 → 移到 Archived

三、階段轉換規則

我們引入了 三階段管理體系：

• Staging：新訓練完成，等待驗證
• Production：穩定上線版本（同一個 base_model 同時僅能有一個）
• Archived：被替換或淘汰的版本

特別處理：Production 衝突

若一個新版本要切換到 Production，系統會：

1. 自動找到同 base_model 的舊 Production
2. 把它轉成 Archived
3. 確保同時只有一個 Production 存在

這樣能避免「多個版本爭搶上線」的混亂情況。

四、API 整合

我們新增了 模型階段轉換 API：

• GET /models/：列出所有模型
• GET /models/search：條件搜尋
• POST /models/recommend：embedding 相似度推薦
• POST /models/transition：切換模型階段

其中 transition API 處理了 MLflow Registry 與本地 Model Card 的雙向同步，確保兩邊的版本/狀態保持一致。

這次優化，讓平台從「能記錄實驗」進化到「能治理模型」。透過 run_id 精確識別，避免版本混淆；Production 衝突能自動歸檔，減少人工操作；MLflow Registry 與 Model Card 狀態保持一致，讓整個模型生命週期（訓練 → 驗證 → 部署 → 歸檔）都能被完整追蹤。

如果說 Day 21 的 Model Card 是「名片」，Day 22 的 Tracking 是「實驗紀錄本」，那麼 Day 23 的 Registry 就是「模型戶籍管理處」，不只回答「有哪些模型」，還能清楚告訴我們：誰在上線、誰剛進場、誰已退休。這一步，平台正式具備了模型治理的基礎能力，為接下來的部署（Day 24）與自動化（Day 25）奠定穩固的基石。

📎 AI 協作記錄：今日開發指令

請幫我針對專案進行以下修改：

1. **整合 MLflow Registry**
   - 修改 `train/runner.py`：
     - 在訓練完成後，呼叫 `mlflow.register_model`，將產生的模型路徑註冊進 MLflow Registry。
     - 註冊時附上 `name`（來自 ModelCard.name）、`version`（自動生成）、`stage`（預設 Staging）。
   - 確保 run_id 與模型 version 有對應關係，並在 ModelCard 中新增欄位：
     ```python
     version: Optional[int] = None
     stage: Optional[str] = None  # Staging / Production / Archived
     run_id: Optional[str] = None
     ```

2. **資料與 artifacts 管理**
   - 在 `train/runner.py` 中：
     - 訓練輸出的 dataset / metrics / model，都上傳至 MinIO（或模擬用本地目錄 `artifacts/`）。
     - 儲存時路徑格式統一為：`artifacts/{run_id}/...`
   - 新增 `tools/artifact_utils.py`：
     - `save_artifact(local_path: str, run_id: str)`
     - `list_artifacts(run_id: str) -> List[str]`

3. **新增 API 路由**
   - 新增 `api/routes/registry.py`，包含：
     - `GET /registry/models`：列出所有已註冊模型（id, name, version, stage, run_id）
     - `POST /registry/promote`：將某模型 version 從 Staging → Production
     - `POST /registry/rollback`：將某模型回滾到指定 version
   - 權限限制：只有 admin 能操作 promote/rollback

4. **更新專案結構**
   - 修改 `app/models/model_registry.py`：
     - ModelCard 增加 version, stage, run_id 欄位
     - `sync_with_mlflow(run_id)`：從 MLflow Registry 拉最新狀態更新 ModelCard

請保留現有功能，確保 ModelCard (Day21) 與 MLflow Tracking (Day22) 對齊，新增 Registry 功能後能讓模型有版本演進與階段切換。